<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Golem examples &mdash; Golem v1.0 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '',
          VERSION:     '1.0',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: ''
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/interface.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="contents" title="Global table of contents" href="contents.html" />
    <link rel="index" title="Global index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Golem v1.0 documentation" href="index.html" />
    <link rel="next" title="Golem API documentation" href="apidoc.html" />
    <link rel="prev" title="Using the Golem library" href="usinglibrary.html" />
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="apidoc.html" title="Golem API documentation"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="usinglibrary.html" title="Using the Golem library"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  
  <div class="section" id="golem-examples">
<h1 id="golem-examples">Golem examples<a class="headerlink" href="#golem-examples" title="Permalink to this headline">¶</a></h1>
<p>Here are some basic examples on how to use Golem to
extract data from CML files. In all of the following, we are using a
dictionary for the <a class="reference external" href="http://www.castep.org">CASTEP</a> code:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="n">golem</span><span class="o">.</span><span class="n">Dictionary</span><span class="p">(</span><span class="s">&quot;castepDict.xml&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">namespace</span> <span class="o">=</span> <span class="s">&quot;http://www.castep.org/cml/dictionary/&quot;</span>
</pre></div>
<div class="section" id="reading-some-data">
<h2 id="reading-some-data">Reading some data<a class="headerlink" href="#reading-some-data" title="Permalink to this headline">¶</a></h2>
<p>In general, to get the data associated with some term within a document:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">getTerm</span><span class="p">(</span><span class="n">doc</span><span class="p">,</span> <span class="n">term</span><span class="p">):</span>
    <span class="n">entry</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="s">&quot;{</span><span class="si">%s</span><span class="s">}</span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">namespace</span><span class="p">,</span> <span class="n">term</span><span class="p">)]</span>
    <span class="n">data</span> <span class="o">=</span> <span class="n">term</span><span class="o">.</span><span class="n">findin</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
    <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">data</span><span class="p">)</span> <span class="o">==</span> <span class="mf">1</span>
    <span class="k">return</span> <span class="n">term</span><span class="o">.</span><span class="n">findin</span><span class="p">(</span><span class="n">doc</span><span class="p">)[</span><span class="mf">0</span><span class="p">]</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
</pre></div>
<p><tt class="docutils literal"><span class="pre">findin</span></tt> always returns a list, so we need to explicitly extract the first
element of the result. One caveat to remember is that there may be no data in
the list, or more than one return value; in those cases, this function will
raise an <tt class="docutils literal"><span class="pre">AssertionError</span></tt>.</p>
</div>
<div class="section" id="dealing-with-multiple-return-values">
<h2 id="dealing-with-multiple-return-values">Dealing with multiple return values<a class="headerlink" href="#dealing-with-multiple-return-values" title="Permalink to this headline">¶</a></h2>
<p>Sometimes, there are many instances of a given concept within a CML file. A
typical example is unit cell dimensions: if you are examining the output of a
geometry optimization, the unit cell will typically be output once for every
step of the calculation, plus once at the start and once at the end.</p>
<p>What if you only want the final unit cell - the converged structure?</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">lastcell</span><span class="p">(</span><span class="n">doc</span><span class="p">):</span>
    <span class="n">ucell_d</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="s">&quot;{</span><span class="si">%s</span><span class="s">}ucell&quot;</span> <span class="o">%</span> <span class="n">namespace</span><span class="p">]</span>
    <span class="k">return</span> <span class="n">ucell_d</span><span class="o">.</span><span class="n">findin</span><span class="p">(</span><span class="n">doc</span><span class="p">)[</span><span class="o">-</span><span class="mf">1</span><span class="p">]</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
</pre></div>
<p><tt class="docutils literal"><span class="pre">findin</span></tt> always returns a list in document order - so the last element in
the list will be the one you want.</p>
<p>Sometimes, however, you can&#8217;t rely on knowledge of document order to find
the particular instance of a concept you&#8217;re looking for. Usually, this is
because the location (or presence) of one concept in a document depends
on the position or value of another. For example, trying to find
the initial volume of the system being simulated:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">initial_volume</span><span class="p">(</span><span class="n">doc</span><span class="p">):</span>
    <span class="n">is_d</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="s">&quot;{</span><span class="si">%s</span><span class="s">}initialsystem&quot;</span> <span class="o">%</span> <span class="n">namespace</span><span class="p">]</span>
    <span class="n">vol_d</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="s">&quot;{</span><span class="si">%s</span><span class="s">}volume&quot;</span> <span class="o">%</span> <span class="n">namespace</span><span class="p">]</span>
    <span class="n">i</span> <span class="o">=</span> <span class="n">is_d</span><span class="o">.</span><span class="n">findin</span><span class="p">(</span><span class="n">doc</span><span class="p">)[</span><span class="mf">0</span><span class="p">]</span>
    <span class="n">v</span> <span class="o">=</span> <span class="n">vol_d</span><span class="o">.</span><span class="n">findin</span><span class="p">(</span><span class="n">i</span><span class="p">)</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
</pre></div>
<p>First, we find the section of the document corresponding to <tt class="docutils literal"><span class="pre">initialsystem</span></tt>;
then we find <tt class="docutils literal"><span class="pre">volume</span></tt> within this, and finally get its value.</p>
</div>
<div class="section" id="terms-with-no-template">
<h2 id="terms-with-no-template">Terms with no template<a class="headerlink" href="#terms-with-no-template" title="Permalink to this headline">¶</a></h2>
<p>Sometimes, <tt class="docutils literal"><span class="pre">getvalue</span></tt> will not work, such as when the term one is looking up
has no defined template (XSLT transform) from its CML serialization to an
object the Golem library understands. In those circumstances, you will see
an error message along the lines of:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">kps</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="s">&quot;{http://www.castep.org/cml/dictionary/}kpoint&quot;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">kps</span> <span class="o">=</span> <span class="n">kpd</span><span class="o">.</span><span class="n">findin</span><span class="p">(</span><span class="s">&quot;/MgRh_18-08.32.31/MgRh-geomopt1.cml&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">kps</span>
<span class="go">[&lt;golem.EntryInstance object at 0x202ce90&gt;]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">kps</span><span class="p">[</span><span class="mf">0</span><span class="p">]</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n-Identifier">?</span>
  File <span class="nb">&quot;/opt/local/Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/site-packages/golem-1.0-py2.4.egg/golem/__init__.py&quot;</span>, line <span class="m">1388</span>, in <span class="n-Identifier">__getattr__</span>
    <span class="k">return</span> <span class="n">etree</span><span class="o">.</span><span class="n">_ElementTree</span><span class="o">.</span><span class="n">__getattribute__</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">tree</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
<span class="nc">AttributeError</span>: <span class="n-Identifier">&#39;lxml.etree._ElementTree&#39; object has no attribute &#39;getvalue&#39;</span>
</pre></div>
<p>In these circumstances, you can locate the fragment of CML containing the
relevant data using Golem, but you&#8217;ll have to extract the data from it
yourself - as here, with <tt class="docutils literal"><span class="pre">&lt;kpoint&gt;</span></tt> . Golem makes use of the <tt class="docutils literal"><span class="pre">lxml</span>
<span class="pre">&lt;http://codespeak.net/lxml&gt;``_</span> <span class="pre">library;</span> <span class="pre">the</span> <span class="pre">objects</span> <span class="pre">retrieved</span> <span class="pre">by</span> <span class="pre">``findin</span></tt>
store the XML they find as <tt class="docutils literal"><span class="pre">obj.tree</span></tt> (as <tt class="docutils literal"><span class="pre">lxml</span></tt> ElementTrees). The
following has been reformatted for legibility&#8217;s sake:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">lxml</span> <span class="kn">import</span> <span class="n">etree</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">kps</span><span class="p">[</span><span class="mf">0</span><span class="p">]</span><span class="o">.</span><span class="n">tree</span><span class="p">)</span>
<span class="go">&#39;&lt;kpointList xmlns=&quot;http://www.xml-cml.org/schema&quot;</span>
<span class="go">  xmlns:castep=&quot;http://www.castep.org/cml/dictionary/&quot;</span>
<span class="go">  xmlns:castepunits=&quot;http://www.castep.org/cml/units/&quot;</span>
<span class="go">  dictRef=&quot;castep:kpoint&quot; title=&quot;k-Point List&quot;&gt;</span>
<span class="go">      &lt;kpoint id=&quot;kpt1&quot;</span>
<span class="go">       coords=&quot;4.583333333333e-1 4.583333333333e-1 4.583333333333e-1&quot;</span>
<span class="go">       weight=&quot;4.629629629630e-3&quot;/&gt;\n [...]</span>
<span class="go"> &lt;/kpointList&gt;&#39;</span>
</pre></div>
<p>So you can interrogate the data using the methods the <tt class="docutils literal"><span class="pre">lxml</span></tt> API gives you,
such as XPath:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">kpoints</span><span class="p">(</span><span class="n">doc</span><span class="p">):</span>
    <span class="n">kpoint_d</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="s">&quot;{</span><span class="si">%s</span><span class="s">}kpoint&quot;</span> <span class="o">%</span> <span class="n">namespace</span><span class="p">]</span>
    <span class="n">kpxml</span> <span class="o">=</span> <span class="n">kpoint_d</span><span class="o">.</span><span class="n">findin</span><span class="p">(</span><span class="n">doc</span><span class="p">)[</span><span class="mf">0</span><span class="p">]</span>
    <span class="n">kps</span> <span class="o">=</span> <span class="n">kpxml</span><span class="o">.</span><span class="n">tree</span><span class="o">.</span><span class="n">xpath</span><span class="p">(</span><span class="s">&quot;cml:kpoint&quot;</span><span class="p">,</span>
                <span class="n">namespaces</span><span class="o">=</span><span class="p">{</span><span class="s">&quot;cml&quot;</span><span class="p">:</span> <span class="s">&quot;http://www.xml-cml.org/schema&quot;</span><span class="p">})</span>
    <span class="n">kpoint_grid</span> <span class="o">=</span> <span class="p">[[[</span> <span class="nb">float</span><span class="p">(</span><span class="n">y</span><span class="p">)</span> <span class="k">for</span> <span class="n">y</span> <span class="ow">in</span> <span class="n">x</span><span class="o">.</span><span class="n">xpath</span><span class="p">(</span><span class="s">&quot;@coords&quot;</span><span class="p">)[</span><span class="mf">0</span><span class="p">]</span><span class="o">.</span><span class="n">split</span><span class="p">()],</span>
                      <span class="nb">float</span><span class="p">(</span><span class="n">x</span><span class="o">.</span><span class="n">xpath</span><span class="p">(</span><span class="s">&quot;@weight&quot;</span><span class="p">)[</span><span class="mf">0</span><span class="p">])</span> <span class="p">]</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">kps</span> <span class="p">]</span>
    <span class="k">return</span> <span class="n">kpoint_grid</span>
</pre></div>
</div>
<div class="section" id="converting-entire-document-sections">
<h2 id="converting-entire-document-sections">Converting entire document sections<a class="headerlink" href="#converting-entire-document-sections" title="Permalink to this headline">¶</a></h2>
<p>We got one piece of data above which happened to be a child of
<tt class="docutils literal"><span class="pre">initialsystem</span></tt>. What if we want all of <tt class="docutils literal"><span class="pre">initialsystem</span></tt>&#8216;s children? We can
get that by iterating over every concept that is a <tt class="docutils literal"><span class="pre">&lt;golem:childOf&gt;</span></tt>
<tt class="docutils literal"><span class="pre">initialsystem</span></tt> as follows:</p>
<div class="highlight"><pre><span class="k">def</span> <span class="nf">getInit</span><span class="p">(</span><span class="n">doc</span><span class="p">):</span>
    <span class="n">v</span> <span class="o">=</span> <span class="p">{}</span>
    <span class="n">i</span> <span class="o">=</span> <span class="n">d</span><span class="p">[</span><span class="s">&quot;{</span><span class="si">%s</span><span class="s">}initialsystem&quot;</span> <span class="o">%</span> <span class="n">namespace</span><span class="p">]</span>
    <span class="n">ikids</span> <span class="o">=</span> <span class="n">i</span><span class="o">.</span><span class="n">getChildren</span><span class="p">()</span>
    <span class="k">for</span> <span class="n">ent</span> <span class="ow">in</span> <span class="n">ikids</span><span class="p">:</span>
        <span class="n">nodes</span> <span class="o">=</span> <span class="n">ent</span><span class="o">.</span><span class="n">findin</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">nodes</span><span class="p">)</span> <span class="o">==</span> <span class="mf">1</span><span class="p">:</span> <span class="c"># check that there&#39;s only one bit of data</span>
            <span class="k">try</span><span class="p">:</span>
                <span class="n">val</span> <span class="o">=</span> <span class="n">ent</span><span class="o">.</span><span class="n">getvalue</span><span class="p">(</span><span class="n">nodes</span><span class="p">[</span><span class="mf">0</span><span class="p">])</span>
                <span class="n">v</span><span class="p">[</span><span class="n">ent</span><span class="o">.</span><span class="n">id</span><span class="p">]</span> <span class="o">=</span> <span class="n">val</span>
            <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
                <span class="c"># we couldn&#39;t convert this</span>
                <span class="k">pass</span>
    <span class="k">return</span> <span class="n">v</span>
</pre></div>
<p>which returns the results as a <tt class="docutils literal"><span class="pre">dict</span></tt>, <tt class="docutils literal"><span class="pre">v</span></tt>, skipping any data we were
unable to convert.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3>Table Of Contents</h3>
            <ul>
<li><a class="reference external" href="">Golem examples</a><ul>
<li><a class="reference external" href="#reading-some-data">Reading some data</a></li>
<li><a class="reference external" href="#dealing-with-multiple-return-values">Dealing with multiple return values</a></li>
<li><a class="reference external" href="#terms-with-no-template">Terms with no template</a></li>
<li><a class="reference external" href="#converting-entire-document-sections">Converting entire document sections</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="usinglibrary.html" title="previous chapter">Using the Golem library</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="apidoc.html" title="next chapter">Golem API documentation</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/examples.txt">Show Source</a></li>
            </ul>
            <h3>Quick search</h3>
            <form class="search" action="search.html" method="get">
              <input type="text" name="q" size="18" /> <input type="submit" value="Go" />
              <input type="hidden" name="check_keywords" value="yes" />
              <input type="hidden" name="area" value="default" />
            </form>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="apidoc.html" title="Golem API documentation"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="usinglibrary.html" title="Using the Golem library"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2008, Andrew Walkingshaw.
      Last updated on Oct 01, 2008.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
    </div>
  </body>
</html>